Allow mode costs to vary by population segment - #405

Motivation

Transport behaviour does not use one set of mode-cost coefficients for every traveller. For example, pupils, households without cars, or residents of a policy area may have different constants, values of time, or distance costs. Until now, modelling that distinction required separate runs or ad hoc project code.

A naive implementation would also run destination and mode search once per population segment. That repeats shared preparation, scales with the number of demand subgroups, and becomes especially wasteful for partial-population assumptions. This PR represents distinct coefficient combinations as compact utility profiles and searches them together.

This PR is stacked on #404 and depends on:

• Batch destination searches across utility profiles mobility-destination-sequence-sampler#2
• Batch mode searches across utility profiles mobility-mode-sequence-search#1

Changes

• Add PopulationSegment definitions to Population, with selectors for country, CSP, home zone, city category, and car ownership.
• Add ParameterValue.by_population_segment() for mode cost constants, costs of time, and costs of distance; segment values can contain scenario and iteration values.
• Support partial shares by splitting represented demand weight before applying max_persons_per_demand_subgroup.
• Resolve the most specific matching segment and reject ambiguous or undefined configurations.
• Deduplicate identical resolved coefficients into utility profiles.
• Compute each distinct generalized-cost table once per iteration and reuse it across destination search, mode search, and final plan scoring.
• Batch all profiles through the Rust destination and mode packages instead of running one model loop per segment.
• Document the modeller-facing behavior in the population, run-parameter, and API guides.
• Require version 0.1.1 of both Rust packages and invalidate affected destination/mode caches.

Example (if relevant)

population = mobility.Population(
    transport_zones,
    sample_size=1_000,
    population_segments=[
        mobility.PopulationSegment(name=pupils, csp=8a),
        mobility.PopulationSegment(
            name=localist_pupils,
            csp=8a,
            share=0.30,
        ),
    ],
)

pupil_cost = mobility.ParameterValue.by_population_segment(
    default=mobility.ParameterValue.by_iteration({1: 20.0, 5: 24.0}),
    segment_values={
        localist_pupils: mobility.ParameterValue.by_scenario(
            default=10.0,
            school_policy=8.0,
        )
    },
)

The 30% subgroup uses the segment value and the 70% complement keeps the default. Both remain in one model run.

AI-assisted contribution

Select one:

• No AI assistance
• AI used for minor help only (e.g. autocomplete, small refactors)
• AI used for substantial parts of this PR

If substantial, briefly describe:

• Scope of AI-assisted content: Public API, demand splitting, parameter resolution, cost-profile preparation, Rust integration, tests, and documentation.
• What you reviewed or changed: Reviewed all three repository diffs for KISS, performance, cache correctness, validation behavior, documentation clarity, and unrelated project-specific files.
• How you validated it (tests, checks, manual verification): 616 Mobility unit tests, 16 integration tests (1 skipped), warning-free Sphinx build, both Rust package suites and release Clippy, plus an end-to-end segmented model run.

Checklist

• I have reviewed all code in this PR
• I understand the code and can maintain it
• I added or ran appropriate tests/checks for the changed behavior